package PagedFile;

public interface PF_FileHandle_Interface {
	
	/*
	 * For this and the following methods, an exception is thrown
	 * if the PF_FileHandle object for which the method is called does not refer to an open file.
	 * This method reads the first page of the file into the buffer pool in memory.
	 * If the page fetch is successful, pageHandle object is returned.
	 * The page read is automatically pinned in the buffer pool,
	 * and remains pinned until it is explicitly unpinned by calling the UnpinPage method.
	 * This method throws an exception when there's no first page.
	 */
	public Buffer GetFirstPage ();
	
	/*
	 * This method reads the last page of the file into the buffer pool in memory.
	 * If the page fetch is successful, a pageHandle object is returned.
	 * The page read is automatically pinned in the buffer pool,
	 * and remains pinned until it is explicitly unpinned by calling the UnpinPage method.
	 * This method throws an exception when there's no last page.
	 */
	public Buffer GetLastPage ();
	
	/*
	 * This method reads into memory the next valid page after the page whose number is current.
	 * If the page fetch is successful, a pageHandle object is returned.
	 * Note that it is not an error if current does not correspond to a valid page.
	 */
	public Buffer GetNextPage (int current_pn);
	
	/*
	 * This method reads into memory the valid page previous to the page whose number is current.
	 * If the page fetch is successful, a pageHandle object is returned.
	 * Note that it is not an error if current does not correspond to a valid page.
	 */
	public Buffer GetPrevPage (int current_pn);
	
	/*
	 * This method reads into memory the page specified by pageNum.
	 * If the page fetch is successful, a pageHandle object is returned.
	 * As usual, the page read is pinned in the buffer pool until it is explicitly unpinned.
	 */
	public Buffer GetThisPage (int pageNum);
	
	/*
	 * This method allocates a new page in the file, 
	 * reads the new page into memory, and pins the new page in the buffer pool.
	 * If the page fetch is successful, a pageHandle object is returned. 
	 */
	public Buffer AllocatePage ();
	
	/*
	 * This method disposes of the page specified by pageNum.
	 * After this method is executed, if you scan over the pages of the file,
	 * the page numbered pageNum will no longer appear.
	 * An exception will be thrown when one attempts to dispose of a page that is pinned in the buffer pool.
	 */
	public void DisposePage (int pageNum);
	
	/*
	 * This method tells the PF component that
	 * the page specified by pageNum is no longer needed in memory.
	 */
	public void UnpinPage (int pageNum);
	
	/*
	 * This method copies the contents of the page specified by pageNum from the buffer pool to disk,
	 * if the page is in the buffer pool and is marked as dirty.
	 * The page remains in the buffer pool but is no longer marked as dirty.
	 * Note that page contents are copied to disk whether or not a page is pinned.
	 */
	public void ForcePages (int pageNum);
	public void ForcePages ();
}
